Basic concept

EchoScript (ES) is a basic, bytecode-compiled language designed to control various aspects of user interface operation in Unsanity Echo. ES scripts are stored in the text form in 'TEXT' resources of an application or skin file and then compiled into bytecode and stored into 'EScr' resources. This means, that once the script has been compiled, you can delete an original 'TEXT' resource to prevent others from peeking at your script code. Might be useful for some skin authors, who knows.

ES scripts are organized in a simple, yet effective manner: there are a fixed number of 'events' that the script wishes to respond to, and a set of commands for each event to be executed once event has occurred. Syntax-wise it looks like this:

EventName
{
<command>
<command>
<command>
}

Commands could be placed only within event brackets; they are separated by carriage returns and can be preceeded by any number of spaces or tabs. Each command can take up various number of arguments. If there are spaces in the argument it is requred to wrap it in single or double quotes (' or ") [Note that curly quotes are not supported, so make sure ResEdit or resorcerer doesnt converts them]. For single-word arguments quotes are not necessary and optional. Arguments are separated by spaces. For example:
beep -takes no arguments
say "Hello world" -takes one argument
say 'Hello world' -takes one arument, single-quotes are acceptable too
dance 'Anna Morgan' "Peter Stein" -takes two arguments, separated by spaces

Event reference

Below are the events available for this build:

Load

called when EchoScript is loaded

Dispose

called when EchoScript is unloaded

Idle
called often at idle time to allow repetetive tasks (but not more often as 2 times per second)

PlayIdle
called often at idle time when some track is playing

PlayStart
PlayStop
called when the playback starts or stops

PlayPause
PlayResume
called when the playback pauses or resumes after a pause

MouseClick
called for controls or windows when user clicks in them

MouseHold
called repeatedly for controls when user clicks in a control and holds mouse

MouseIn
MouseOut
called when mouse enters or exists control area

SliderDrag
called repeatedly when user changes slider value. only effective for slider controls.

BusyBegin
BusyEnd
called when Echo starts or ends scanning files to be added to the database

Busy
called repeatedly when Echo scans files to be added to the database

TotalTimeUpdated
called when Echo updates database total time value

ShiftMouseClick
CmdMouseClick
OptionMouseClick
ShiftCmdMouseClick
ShiftOptionMouseClick
CmdOptionMouseClick
ShiftCmdOptionMouseClick
called when user clicks while holding one or more of the modifier keys

Command Reference

Log "<text to write into log file>"

writes an entry to the log file

Error "<error to write into log file>"
writes an error entry to the log file

Beep [no arguments]
performs a system alert sound

Play [no arguments]
starts playback

Pause [no arguments]
pauses or resumes playback

Stop [no arguments]
stops playback

Show <control reference>
Hide <control reference>
shows or hides pane which ID is specified in the argument, or itself if the argument is 'me' (show me, hide me).

Enable <control reference>
Disable <control reference>
enables or disables pane which ID is specified in the argument, or itself if the argument is 'me' (enable me, disable me)

ShowWindow <window id>
HideWindow <window id>
shows or hides windows with the specified id. if window does not exist, it creates it.

CloseWindow <window id>
closes window with the specified id. This is different from HideWindow as it actually disposes window instead of just hiding it.

ResizeWindow <window id>
starts the process of tracking mouse to allow user resize the window

SetValue <control reference> <control value or global>
sets value of a pane specified in 1st argument to the value specified in 2nd. If 2nd argument begins with # (for example, #123), the value is considered numeric, otherwise it considered text value. can set itself if first argument is 'me' (setvalue me #123).

SetTrackPos <absolute or relative position>
changes track position of currently playing track. argument can be in range of 0 to 100. If argument is preceeded by plus or minus sign, position is considered relative to current one.

SetInfoline <control reference> <contents>
sets referenced infoline to given contents. contents could be either a string, or one of the 'constant' values - InfolineBlank, InfolineBrief, InfolineFull.

SetInfolineSpeed <control reference> <speed>
sets infoline speed. negative values moves infoline slower than positive, and are controlled by internal timers; positive values scroll the line by the given offset every tick.

SetBrowserWindowID <window id>
SetPlaylistWindowID <window id>
sets window id's to be used as browser and playlist windows. While Echo does not depend on window or control IDs generally, it needs to know browser and playlist window IDs to show them when user asks to.

PreviousPreset
NextPreset
switches to previous or next preset in EchoVision area.

ToggleTimer
toggles between normal and reversed timer mode.

SetVolume <absolute or relative volume>
sets current volume. If argument is preceeded by plus or minus sign, volume is considered relative to the current.

RecentItemsPopup
invokes recently played tracks popup menu.

Arguments Reference

<control reference>
an id of control to set, or, if control is located in another window, and id of the window, slash, and id of the control. There is also a possibility to set a value of the control owning script by providing 'me' as a value. Control IDs are case-sensitive. Examples:
abcd - references control in the same window with id 'abcd'
128/abcd - references control in window id 128 with id 'abcd'
me - references control owning the script

<window id>
an id of the window as defined in Constructor

<control value>
string representing the value, or, if value is numeric, a number preceeded by # sign. Examples:
"some value" - identifies value "some value"
#1234 - identifies numeric value 1234

<global>
special name representing global variable holding some data about current Echo state. A list of globals is provided below under the topic 'Globals'

Globals Reference

Globals can either reference a string or a numeric value. Globals are not case sensitive. Below are the list of currently defined globals:

TrackPos [numeric]
current position inside a playing track, in percent.

TrackTime [numeric]
current track timer value, in seconds.

TrackTimeDigit1 [numeric]
TrackTimeDigit2 [numeric]
TrackTimeDigit3 [numeric]
TrackTimeDigit4 [numeric]
current track timer value, individually selected for a given timer digit.

TrackTitle [string]
TrackArtist [string]
TrackAlbum [string]
TrackYear [string]
TrackKind [string]
various aspects of current track information, if available

TrackMixRate [numeric]
current track mix rate, in khz

TrackBitRate [numeric]
current track bitrate

TrackInstruments [numeric]
current track instruments list (useful for MOD-kind tracks with an instrument set)

BusyProgress [numeric]
value in percents (0-100) of the files scanned relative to total files pending when Echo is in busy state (see BusyBegin/BusyEnd/Busy events)

TotalTracks [numeric]
number of all tracks in the database

TotalTime [numeric]
total time of all tracks in the database

Volume [numeric]
current volume